/**
 * @file transport_net.h
 * @brief 网络传输驱动头文件
 * @details 本文件定义了通用的网络传输驱动接口和数据结构。
 *          提供基于TCP/UDP协议的网络传输功能，不包含任何协议特定逻辑。
 * 
 * @author 电网协议开发团队
 * @date 2024
 * @version 1.0
 */

#ifndef TRANSPORT_NET_H
#define TRANSPORT_NET_H

#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif

/* ==================== 网络传输驱动类型定义 ==================== */

/**
 * @brief 网络传输错误码
 */
typedef enum {
    NET_TRANSPORT_SUCCESS = 0,              /* 成功 */
    NET_TRANSPORT_ERROR_INVALID_PARAM,      /* 无效参数 */
    NET_TRANSPORT_ERROR_INIT_FAILED,        /* 初始化失败 */
    NET_TRANSPORT_ERROR_CREATE_FAILED,      /* 创建失败 */
    NET_TRANSPORT_ERROR_CONNECT_FAILED,     /* 连接失败 */
    NET_TRANSPORT_ERROR_DISCONNECT_FAILED, /* 断开失败 */
    NET_TRANSPORT_ERROR_SEND_FAILED,       /* 发送失败 */
    NET_TRANSPORT_ERROR_RECEIVE_FAILED,     /* 接收失败 */
    NET_TRANSPORT_ERROR_TIMEOUT,           /* 超时 */
    NET_TRANSPORT_ERROR_NOT_CONNECTED,     /* 未连接 */
    NET_TRANSPORT_ERROR_ALREADY_CONNECTED, /* 已连接 */
    NET_TRANSPORT_ERROR_MEMORY,            /* 内存错误 */
    NET_TRANSPORT_ERROR_SYSTEM,            /* 系统错误 */
    NET_TRANSPORT_ERROR_UNKNOWN            /* 未知错误 */
} net_transport_error_t;

/**
 * @brief 网络传输状态
 */
typedef enum {
    NET_TRANSPORT_STATUS_DISCONNECTED = 0,  /* 未连接 */
    NET_TRANSPORT_STATUS_CONNECTING,        /* 连接中 */
    NET_TRANSPORT_STATUS_CONNECTED,         /* 已连接 */
    NET_TRANSPORT_STATUS_DISCONNECTING,    /* 断开中 */
    NET_TRANSPORT_STATUS_ERROR              /* 错误状态 */
} net_transport_status_t;

/**
 * @brief 网络传输配置
 */
typedef struct {
    char server_ip[64];          /* 服务器IP地址 */
    uint16_t server_port;       /* 服务器端口 */
    uint16_t local_port;         /* 本地端口 */
    uint32_t timeout_ms;         /* 超时时间(毫秒) */
    uint32_t retry_count;        /* 重试次数 */
    bool keep_alive;            /* 保持连接 */
    uint32_t heartbeat_interval; /* 心跳检测间隔(毫秒)，0表示不启用 */
    uint32_t heartbeat_timeout;  /* 心跳超时时间(毫秒)，超过此时间无响应认为连接断开 */
} net_transport_config_t;

/**
 * @brief 网络传输统计信息
 */
typedef struct {
    uint64_t bytes_sent;         /* 发送字节数 */
    uint64_t bytes_received;    /* 接收字节数 */
    uint64_t packets_sent;      /* 发送包数 */
    uint64_t packets_received;  /* 接收包数 */
    uint64_t errors;            /* 错误数 */
    uint64_t timeouts;          /* 超时数 */
} net_transport_stats_t;

/**
 * @brief 网络传输回调函数类型
 */
typedef void (*net_transport_receive_callback_t)(const uint8_t* data, size_t length, void* user_data);
typedef void (*net_transport_status_callback_t)(net_transport_status_t status, void* user_data);
typedef void (*net_transport_error_callback_t)(net_transport_error_t error, void* user_data);

/* ==================== 网络传输驱动函数声明 ==================== */

/**
 * @brief 初始化网络传输驱动
 * @details 初始化网络传输驱动
 * 
 * @return 网络传输错误码
 */
net_transport_error_t transport_net_init(void);

/**
 * @brief 清理网络传输驱动
 * @details 清理网络传输驱动
 * 
 * @return 网络传输错误码
 */
net_transport_error_t transport_net_cleanup(void);

/**
 * @brief 创建网络传输实例
 * @details 创建网络传输实例
 * 
 * @param config 网络配置
 * @return 传输实例指针，失败返回NULL
 */
void* transport_net_create(const net_transport_config_t* config);

/**
 * @brief 销毁网络传输实例
 * @details 销毁网络传输实例，清理相关资源
 * 
 * @param instance 传输实例
 * @return 网络传输错误码
 */
net_transport_error_t transport_net_destroy(void* instance);

/**
 * @brief 连接网络传输
 * @details 建立网络传输连接
 * 
 * @param instance 传输实例
 * @return 网络传输错误码
 */
net_transport_error_t transport_net_connect(void* instance);

/**
 * @brief 断开网络传输
 * @details 断开网络传输连接
 * 
 * @param instance 传输实例
 * @return 网络传输错误码
 */
net_transport_error_t transport_net_disconnect(void* instance);

/**
 * @brief 获取网络传输状态
 * @details 获取网络传输的当前状态
 * 
 * @param instance 传输实例
 * @return 网络传输状态
 */
net_transport_status_t transport_net_get_status(void* instance);

/**
 * @brief 网络传输发送数据
 * @details 通过网络传输发送数据
 * 
 * @param instance 传输实例
 * @param data 要发送的数据
 * @param length 数据长度
 * @return 网络传输错误码
 */
net_transport_error_t transport_net_send(void* instance, const uint8_t* data, size_t length);

/**
 * @brief 网络传输接收数据
 * @details 从网络传输接收数据
 * 
 * @param instance 传输实例
 * @param buffer 接收缓冲区
 * @param max_length 最大接收长度
 * @param actual_length 实际接收长度
 * @return 网络传输错误码
 */
net_transport_error_t transport_net_receive(void* instance, uint8_t* buffer, size_t max_length, size_t* actual_length);

/**
 * @brief 设置网络传输接收回调
 * @details 设置网络传输数据接收回调函数
 * 
 * @param instance 传输实例
 * @param callback 回调函数
 * @param user_data 用户数据
 * @return 网络传输错误码
 */
net_transport_error_t transport_net_set_receive_callback(void* instance, net_transport_receive_callback_t callback, void* user_data);

/**
 * @brief 设置网络传输状态回调
 * @details 设置网络传输状态变化回调函数
 * 
 * @param instance 传输实例
 * @param callback 回调函数
 * @param user_data 用户数据
 * @return 网络传输错误码
 */
net_transport_error_t transport_net_set_status_callback(void* instance, net_transport_status_callback_t callback, void* user_data);

/**
 * @brief 设置网络传输错误回调
 * @details 设置网络传输错误回调函数
 * 
 * @param instance 传输实例
 * @param callback 回调函数
 * @param user_data 用户数据
 * @return 网络传输错误码
 */
net_transport_error_t transport_net_set_error_callback(void* instance, net_transport_error_callback_t callback, void* user_data);

/**
 * @brief 获取网络传输统计信息
 * @details 获取网络传输统计信息
 * 
 * @param instance 传输实例
 * @param stats 统计信息输出
 * @return 网络传输错误码
 */
net_transport_error_t transport_net_get_stats(void* instance, net_transport_stats_t* stats);

/**
 * @brief 重置网络传输统计信息
 * @details 重置网络传输统计信息
 * 
 * @param instance 传输实例
 * @return 网络传输错误码
 */
net_transport_error_t transport_net_reset_stats(void* instance);

/**
 * @brief 获取网络传输错误字符串
 * @details 获取网络传输错误码对应的字符串描述
 * 
 * @param error 错误码
 * @return 错误字符串
 */
const char* transport_net_get_error_string(net_transport_error_t error);

#ifdef __cplusplus
}
#endif

#endif /* TRANSPORT_NET_H */
